// Copyright (c) 2010, Anthony Cassidy
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without modification, are 
// permitted provided that the following conditions are met:
// 
//     * Redistributions of source code must retain the above copyright notice, this list 
//         of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright notice, this 
//         list of conditions and the following disclaimer in the documentation and/or 
//         other materials provided with the distribution.
//     * Neither the name of the AntsAdventureGameCreator nor the names of its contributors 
//         may be used to endorse or promote products derived from this software without 
//         specific prior written permission.
// 
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
// SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
// THE POSSIBILITY OF SUCH DAMAGE.

/*!
@page Example7
<h1>Example 7 - Using the Codes</h1>
<h2>Summary</h2>
As you've seen so far the system relies on the code using
the folder names of the folder on disk. This has a few pitfalls:
- a simple typo can break things.
- changing the name of a folder will break things.

<br>
The following series of steps will show you how to use
ROOMDECLARATION_WITH_CODES() to add compile time keyword checking.

<h2>Steps</h2>
<ol>

<li>
<h2>Change from ROOMDECLARATION() to ROOMDECLARATION_WITH_CODES() </h2>
You may need to add an include to ROOMDECLARATION_WITH_CODES.h.
</li>


<li>
<h2>Add a ROOMDECLARATION_FOR_CPP() macro just beneath it</h2>
You will need to add an include to ROOMDECLARATION_FOR_CPP.h.
</li>


<li>
<h2>For all RoomObjects, add DEF(keyword) declarations somewhere before ROOM_DECLARATION_FOR_CPP </h2>
You will need to add an include to DEF.h
</li>

<li>
<h2>For all InventoryObjects, add INVDEF(keyword) declarations somewhere before ROOM_DECLARATION_FOR_CPP</h2>
You will need to add an include to INVDEF.h
</li>


<li>
<h2>For all Animations, add ANIMDEF(keyword) declarations somewhere before ROOM_DECLARATION_FOR_CPP</h2>
You will need to add an include to ANIMDEF.h
<br>
<br>
What you have now should look something like this:
<img src="Example7_1.png">
If you try to compile now, you will still find three errors (see below).
The errors exist because the ROOMDECLARATION_WITH_CODES() uses
OnCommandLineExecuteWithCodes(), insted of using OnCommandLineExecute().
OnCommandLineExecute represents the verbs and nouns of a command as strings, whilst
OnCommandLineExecuteWithCodes combined these in to a single number. The single
number approach is useful because it can be handled using a switch statement.

The next step is to switch to using OnCommandLineExecuteWithCodes().

<img src="Example7_2.png">
</li>

<li>
<h2>Switch to using OnCommandLineExecuteWithCodes()</h2>
<br>
OnCommandLineExecuteWithCodes(int number, int x, int y)
combined the verb and the objects of OnCommandLineExecute()
in to a single number. The number is calculated as follows:
- verb + objectA  (for verbs that take one single object)
- verb + objectA * objectB (for verbs that take two objects);

<br>
OnCommandLineExecuteWithCodes() can be implemented
using a big switch statement with sentences as the case statements (see below)
<br>
The case statements can be made to look even more like sentences, by
using the enum contained in #VerbEnumeration or the macros
contained in VerbMacros.h.
This allows you to remove the '+' statement from the case statements (see @ref Example8).
</ol>

<img src="Example7_3.png">
<br>
<br>
On to @ref Example8...
*/

